🎯 What We'll Cover
Enough framing — this lesson gets your hands on the tool. We do a first real session against a deliberately messy research archive, the kind every researcher actually has. You will inspect it without changing anything, see exactly how Claude Code asks permission before it touches a file, run the debrief that turns the exercise into a lesson, and meet CLAUDE.md — the file that steers every session and becomes, in Lesson B, the device that enforces reproducible habits.
Setup is deliberately out of scope here: installation changes too often to print. Install Claude Code from the official documentation at docs.claude.com, confirm it runs, and come back.
📁 The Sample Project: A Messy Research Archive
Throughout this track we use one fictional running example: the Berg River microplastics study. A postgraduate has collected water samples at three sites — upstream of a town, in the town, and downstream — and counted microplastic particles across a sampling season. Wherever you see “microplastic counts,” read your own measurements; the structure is what matters, not the subject.
The starting archive is realistically messy, because real ones are. Inconsistent column names across files, counts at one site that are quietly wrong in a way only the field notes explain, a confusingly named “final-v2” file with no v1 in sight, a contaminated outlier and some missing values, free-text field notes that explain anomalies the spreadsheets don’t, and a stale README referring to files that no longer exist:
berg-river-microplastics/
data/raw/
site-upstream.csv # one naming convention...
site_town.csv # ...different columns, DD/MM/YYYY dates
downstream-final-v2.csv # third naming; blank cells; one oddly high value; where is v1?
sampling-metadata.csv # site coordinates, dates, methods
field-notes.md # free text; explains anomalies the CSVs don't
literature-notes.md # half-organised reading notes
README-old.txt # stale; refers to files that are gone
This is the perfect first task because the danger is obvious: you do not want an over-eager agent “tidying” your only copy of the raw data before you have understood it. So the first thing we do is the opposite of letting it loose.
📥 Download: the Berg River sample archive
Grab the deliberately-messy starting files and open the folder in Claude Code to follow along: berg-river-microplastics.zip. The same archive drives the full reproducible analysis in Lesson B.3. Equally good for this first inspect-only exercise — and arguably better — is to point Claude Code at a real messy folder of your own, provided you have a backup and you keep the agent in inspect-only mode throughout.
👀 Your First Task: Inspect, Don't Change
Open a terminal in the project folder and start Claude Code:
cd berg-river-microplastics claude
Then give it an inspection-only task. The wording matters — it explicitly forbids changes:
> Inspect this folder before changing anything. Tell me what files
are here, what each appears to contain, what you should not edit,
and what you would recommend doing first. Do not move, rename, or
edit anything yet.
Better still, put Claude Code into plan mode first (Claude Code lets you toggle a read-only planning mode in which it can look but cannot act). In plan mode the agent physically cannot edit a file — it can only inspect and propose. For a first encounter with a folder you care about, that guarantee is worth having rather than relying on the wording of your prompt alone.
👁 What to watch while it works
- Does it actually read the files before making claims about them, or does it guess from the names?
- Does it separate what it observed from what it inferred — “this column is labelled pH” versus “this is probably pH”?
- Does it flag the contradictions (the field notes versus the CSVs) rather than silently picking one?
- When it wants to do something, does it propose it and wait, or just do it?
- Which permissions does it ask you for, and which did you grant?
🔐 Permissions and Plan Mode
This is the moment to understand Claude Code's safety model, because it is what makes handing an agent your files defensible rather than reckless.
Permission prompts
By default, Claude Code asks before it does anything consequential — editing a file, running a command. You see what it intends and approve or decline. The default posture is “ask first,” and for research work you should keep it that way until you have reason not to.
Plan mode
A read-only mode: the agent inspects and produces a plan but cannot change anything. Use it for any first contact with real data, and for any step whose consequences you cannot easily reverse. It is the cheapest insurance in the tool.
Allowlists
Once you trust a category of action — say, running your read-only inspection script — you can allow it without re-approving each time. The skill is allowlisting the genuinely safe and routine, never the destructive. (Your own projects, the survey showed, allowlist exact commands, not blanket access.)
The sandbox boundary
Claude Code works in the folder you point it at. It does not roam your whole machine by default. Keep raw, sensitive, or irreplaceable material outside the working folder, or explicitly marked read-only, and the blast radius of any mistake stays small.
🔒 What Leaves Your Machine
The permissions model governs what the agent may do to your files. There is a second question it does not answer, and for research data it is the more important one: what leaves your machine? Claude Code runs in your terminal, but the model does not. When the agent reads a file, that file's contents are sent to Anthropic's API for the model to process — that is how it “sees” them at all. Pointing the agent at a folder is, in effect, sending that folder's contents to a third party. For a great deal of research that is completely fine. For some of it, it is the whole question.
⚠️ Before you point an agent at confidential data
If your data is human-subjects data under an ethics approval, personal data under POPIA or the GDPR, or covered by an NDA or a data-use agreement, you carry an obligation that is entirely separate from how good the tool is: establish whether sending it to a third-party service is permitted at all. Your ethics clearance or data agreement may forbid external processing, require de-identification first, or demand specific contractual terms. That is yours to confirm before the first claude in that folder — not the tool's, and not an afterthought.
Two things are worth keeping separate. First, the provider's data-usage terms — whether your inputs are retained or used to improve models. For Anthropic's commercial and API products the default is that they are not used for training; the consumer subscription plans are governed separately, and those settings have changed over time. So apply the Week 9 habit and read the current data-usage terms for your plan rather than trusting a claim a course page wrote months ago. Second, and independent of that: your own obligations. Even a provider that never trains on your data is still a third party your ethics approval may not permit you to send participant data to. The training question and the permission-to-send question are different, and you have to clear both.
In practice, a few habits keep you on the right side of this:
State the data's status
Put it at the very top of CLAUDE.md — “real, human-subjects; do not share externally” versus “public; fine to process.” It reminds you each session, and it tells the agent the stakes it is working under.
Work on extracts, not the originals
Where you can, point the agent at de-identified, sampled, or synthetic data and keep the identifiable originals out of the working folder entirely. The agent can only transmit what it can read.
Keep secrets out of the folder
API keys, passwords, tokens: an agent that reads a config file reads those too. Keep them in environment variables, never in the working tree, and .gitignore anything sensitive so it is neither read nor committed.
Mind what you commit
Never commit participant data or credentials to a repository — especially a public one. A .gitignore covering data/raw/ and any secrets stops one careless commit from becoming a permanent, published mistake.
💬 The Debrief
When the inspection is done, ask the question that converts the exercise into a transferable habit:
> What did you inspect, what did you infer, and what would you
change only after my approval?
A good answer cleanly separates the three. Inspected: the files it actually opened and what they contained. Inferred: the educated guesses — that “final-v2” supersedes a missing v1, that two values are data-entry errors. Would change only with approval: every rename, merge, and correction it is recommending but has not done. If the agent blurs these together, that is itself the finding: it is exactly the “evidence versus guess” line that Week 9 spent a whole sub-lesson on, now showing up in a tool instead of a chat.
📝 CLAUDE.md: The Control Surface
You will not want to retype “don't touch the raw data, separate evidence from inference, ask before editing” at the start of every session. You should not have to. That is what CLAUDE.md is for: a plain-Markdown file at the root of your project that Claude Code reads automatically at the start of every session. It is the standing instruction set — the single most important file for steering the agent, and the thing that makes the next session behave like the last one.
You can generate a starter with the /init command, which inspects the project and drafts a CLAUDE.md for you to edit. A minimal one for the Berg River project might begin:
# CLAUDE.md — Berg River microplastics study ## Working rules - Read files before proposing changes. - Never modify anything in data/raw/. It is the only copy. - Use plan mode and show me the plan before any consequential change. - When you summarise or analyse, name which files you used. - If something is uncertain, say so — do not fill the gap with a guess. - Save scripts in scripts/ and generated outputs in outputs/. - Before you tell me a task is done, show me the diff.
One piece of vocabulary, since it recurs: a diff (short for “difference”) is the set of exact lines that changed between the old and new version of a file — what was removed and what was added — rather than the whole file. So “show me the diff” means show me precisely what you changed, not a description of it. It is the cheapest way to see what an agent actually did, and how to use it well at scale is a question we return to in Lesson B.3.
💡 This is the hinge of the whole track
Notice what just happened. Every one of those lines is a research-integrity habit this course already taught — “do not fill the gap with a guess” is the Week 9 hallucination lesson; “name which files you used” is the Week 5 citation lesson; “show me the diff” is verification. Written into CLAUDE.md, they stop being good intentions and become rules the agent follows every time. Lesson B turns this short file into the full reproducibility-enforcement template — the headline artefact of the track.
🧠 Sessions, Memory, and Starting Fresh
One practical thing about how Claude Code behaves over a long task. A session has a finite context window — the amount it can hold in working memory at once. A morning's analysis can fill it, and as it fills, the agent starts to lose track of what was said early on. This sounds like a limitation, and in part it is. It is also where this track's organising principle quietly pays off.
Because the chat is not the archive, you are never dependent on the conversation surviving. The project state lives on disk: the CLAUDE.md (re-read automatically at the start of every session), the decision log, the scripts, the Git history. So you can end a bloated, drifting session and start a clean one whenever you like — quit, run claude again, and the new session picks the project up from the files, not from a transcript you have lost. A fresh session pointed at a well-kept folder is often sharper than a long one that has wandered.
💡 The corollary of “the chat is not the archive”
If losing the conversation would lose your work, your work is in the wrong place. In a well-kept project folder the conversation is disposable by design: you commission the work in the chat, it lands in the files, and the next session starts fresh from those files. This is also why committing at milestones matters — a brand-new session can read the Git history and the decision log and see exactly where things stand, with no memory of the chat required.
✅ What to take from Lesson A
Claude Code is a model with hands in your project folder — the harness, not the model, is what you are driving. The work lives in files, not in the chat. It costs money and excludes some researchers, and we said so. Using it well is a shift from prompting to managing: delegate, checkpoint, verify, and scaffold in proportion to the stakes. And CLAUDE.md is where your standing rules live.
Lesson B is the reason the track exists: turning all of this into research that someone else can inspect and repeat — reproducibility, made concrete.